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PS8IN, PS80UT 


DE CUS Program Library Write-up DECUS NO. 8-472 

1 PROGRA M D ESCRIPTION 

In order to avoid the elaborate PS8 input-output programming, which pre¬ 
supposes a thorough knowledge of PS8 User Service Routines, we tried to design 
an automatic routine which would appear to the user as a simple character- 
oriented device like the TELETYPE. 

A JMS to the input part would return the next character, and a JMSto the output 
part would "print" it on the output-file and -device. 


The routine should for example, be able to call the COMMAND DECODER and 
detect when to close the output file. 


The routines were designed for a typical class of programs expecting one input 
source and one output drain, and working with 8 bit structures - only (ASCII; 
BINARY) 


In this class of files the terminating character CTRL/Z(232) plays an important 
role, making the following automatic concept possible: 


When entered for the first time, the INPUT part (PS8IN) calls the COMMAND 
DECODER; fetches the device-handler; reads the first block; and takes the first 
character to return to the user. In successive calls, the routine reads blocks, 
takes characters from it etc. until a CTRL/Z is detected. It then opens the next 
input file and so on, until no input files remain. It then passes the CTRL/Z 
character for the first time, signaling the real end-of-file situation. 


The OUTPUT part (PS80UT) fetches the device handler and opens the output file^ 
when entered for the first time. It then writes the character away in the output 
buffer. In successive calls the output buffer will be filled and buffers will be 
written to the output device. 

Passing a CTRL/Z character to the OUTPUT part closes the output file, and 
causes an automatic return to the MONITOR. 


The main benefits of these building blocks are that they provide bug-free operation, 
and meaningful error messages when errors are detected. The programmer is also 
relieved from the bookkeeping of blocks on the input and output. They can also 
be used to adapt 4K programs to the PS8 programming system. 


specified to the COMMAND DECODER 






The input to the COMMAND DECODER is: 


* outdev:.FILE <*~indev: FILE 1, FILE 2,.. FILE 9 

The use of the options (/,(), -) is still the same. If more than one output was 
specified, only the first one will be taken, and no error message results. The 
maximum number of input files is 9. 


The routines were compacted, each to fit into one physical page of core. They 
are page-relocatable at assembly-time, and they can easily be dimensioned with 
regard to buffer size and the place of one- and two-page handlers. By compacting 
the routines, however, some restrictions were implemented too: the routines must 
reside in FIELD 1, as is the case with the buffers. This was not felt as a major 
disadvantage. The routines are not restartable, however. 
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HOW TO USE PS8IN and PS80UT 


An example of a program to perform the /A or /B option in PIP is attractively 
simple: 

START, CIF 10 

JMS I (PS8IN /call C.D. and fetch a char. 

CIF 10 

JMS I (PS80UT /output the char. 

JMP START 


Note that the exit to the PS8 monitor is also built-in: the last character (CTRL/Z) 
closes the output file, and then causes a jump to the monitor. 

If the input file has no CTRL/Z as a terminator, PS8IN reads all characters of the 
last block, and automatically generates one CTRL/Z when trying to read beyond 
the file limits. This occurs only once 1! 


Parameters can be set in the‘bser-equates" at the beginning of each module. 
For PS80UT the following applies: 


TWO PAG = 1 . . . . . allows a two-page handler to be loaded in core. The 

user himself must be sure that the handler area is in 
agreement with this statement. 

TWOPAG = 0 .means that only one-page handlers are allowed. 
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HANDLE = 7200 Defines where the device-handler should be loaded in 

core. Note that device handlers are always loaded in 

FIELD jar. 


BUFOUT = 6600 ) 
BLKOUT = 1 ) 


Define the buffer area. In this example a buffer of one 
BLOCK (= 2 pages) beginning at 16600 and ending at 
17200 is specified. 

Note that the buffer resides in FIELD 1, \Ahich is a 
must. 

The buffer may, however, be located in the COMMAND 

DECODER area. i 

One can use any multiple of 1 BLOCK as a buffer size. 


For PS8IN similar equates exist: 


INTPAG = 1 
INTPAG = 0" 
HAND IN =7000 


For a two-page handler. 

For an one-page handler. 

The beginning of the handler area. Be careful not 
to load over the monitor resident areas, as no protection 
against this offence exists. 


BUFIN = 6200 ) 

BLOK IN = 1 ) 


PSEXT = 0123 


Define a buffersize of 1 BLOCK (2 pages) from 16200 to 
16600 in FIELD 1. 

The input buffer also must reside in FIELD 1. It may, 
however, be located in the COMMAND DECODER area. 
The buffer size can be any multiple of 1 BLOCK. 

Defines a default extension (.AS) if no extension was 
specified in the input file. For example: if the user typed 
* SYS: TRY SYS:TEM 

the COMMAND DECODER searches the filename 
TEM.AS prior to the filename without an extension. 
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PS8IN and PS80UT as structured in the available listings occupy core as 
follows: 


0 


7000 

7200 

7600 

7777 


FIELD 0 


INPUT 

HANDLER 

TP 

OUTPUT 

HANDLER 

MONITOR 

““V 


1000 


16200 

16600 

ONE 17200 
PAGE. 17400 

17600 

17777 


FIELD 1 


INPUT 

BUFFER 


OUTPUT 

BUFFER 


PS8 OUT 
S8 IN 


MONITOR 


When the user detects the CTRL/Z himself, he may suspend the termination of 
the program. He should, however, cause a monitor return with the CTRL/Z 
character to PS80UT, in order to close the file. 

If other devices were used in the program, he should clear the hardware flags 
before terminating the program. This is to prevent "unexpected interrupts" to occur 
in programs that do not use these devices, while running with the interrupt on. 

Although PS8IN and PS80UT were designed to run together, they can nevertheless 
be used separately. PS8IN, when used alone, will be quite self-supporting: it calls 
the COMMAND DECODER, and sets the JOB STATUS word to prevent the restart 
of the program. 

The use of PSSOUT alone needs more help: as the command-decoder is not called 
automalically, the user should do so himself. He should also set the JOB STATUS 
word to prevent a restart of the program. 
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For a COMMAND DECODER call: 


CIF 1 0 
JMS I (7700 
5 

PSEXT /Default extension 0123 = AS 

/Return. 

To set the JOB STATUS word bit 2 (not restartable): 

CDF 0 

TAD I (7746 /Do an inclusive OR. 

AND (6777 
TAD (1000 
DCA I (7746 


Instead of using the command decoder, the user can write to a fixed file on a 
fixed device, by filling in locations 17600 to 17604 of the output file table 
(chapter 3.4.1 of the PS8 software support manual). An example of a fixed output 
file, named TEM.FD on the system-device (device 1) follows below: 


17600 

17601 

17602 

17603 

17604 


0001 /length undetermined; device^l 

2405 /TE 

1500 /M 

0000 

0604 /. FD 


For the device numbers see appendix 4.2. 

Note that PSSOUT can not be used to delete an existing file. The user can delete 


an existing (or not existing) file as follows: 


The user wants to delete the file TEM.FD on the system-device (device-number 1) 


TAD 

(1 

/DEVICE NUMBER 

CIF 

10 


JMS 1 

1 (7700 

/CALL USR 


4 

/CLOSE 


NAME 

/POINTER TO NAME ’'TEM.FD" 


0 

/ZERO BLOCKS = DELETE 


/IF TEM.FD NOT FOUND IS O.K. TOO. 


NOP 




NAME, FILENAME TEM.FD 


Note that the 4-word name block should be located in the field of the 
USR-cal I. 

LIMITATIONS 

The limitations of PS3IN and PS80UT are listed here, point by point 

1) The program works in FIELD 1 only; it may not be loaded into 10000-11777 
or 17600-17777. 

2) Input and output buffers in FIELD 1 only. They may, however, be located in 
the COMMAND DECODER area. 

3) Device-handlers in FIELD 0 only (restriction of PS8). 

4) The program is not restartable. 

5) PS80UT is not fully self-supporting (COMMAND DECODER) 
and JOB STATUS word) when used alone. 

6 ) Only ASCII and BINARY files can be processed. 

7) All error messages are fatal; they cause a MONITOR return. 

8 ) The size of the output file will always be a multiple of the output buffer. 
When closing a file, the remaining blocks v/ill be filled with zeroes. 

The use of small buffers minimizes this "rounding off". 

9) PS80UT cannot be used to delete a file. 





4.1 A SUMMARY OF ERROR-MESSAGES 


All PS8IN and PS80UT error-messages are fatal. They are printed by the user 
service routines in the following format: 

USER ERROR N AT XXXXX 

Where N is the error code, explained below, and XXXXX is related to a location 
in core where the error call came from. As all error calls come from the same 
2 origins in PS8IN and PS80UT, XXXXX has no meaning to the user. 

USER ERROR 1: The output-device handler could not be found; An attempt was 



made to load a 2-page handler into one page. 

USER ERROR 2: The output file could not be opened or closed; the device was a 


read only device; No room for output; two tentative files on 
this device; An illegal device name was specified. 


USER ERROR 3: Output file too long. 

USER ERROR 4: Write error in output. 

USER ERROR 5: The input-device handler could not be found. 
USER ERROR 6: Read error in input. 
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4.2 DEV1CENNUMBERS IN PS8 


DEVICE 

NUMBER 

DEVICE 

01 

SYSTEM-DEVICE 

02 

DEFAULT DEVICE "1 

03 

TELETYPE PRINTER 

04 

LINE PRINTER 

05 

DECTAPE 0 

06 

" 1 

07 

" 2 

10 

" 3 

11 

" 4 

12 

" 5 

13 

" 6 

14 

" 7 

15 

PAPERTAPE PUNCH 

16 

PAPERTAPE READER 

17 

CARD READER 


If 
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The author(s) will be grateful when detected errors in both software performance 
and the manual are reported back. 

In such a case, please write to the author(s): 

MEDICAL BIOLOGICAL LABORATORY TNO 
Computer department c/o Mr. J.F. Anthoni 
139, Lange Kleiweg 
RIJSWIJK 2100, P.O. Box 45 
THE NETHERLANDS 
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PS8IN, PS80UT 



DE CUS Program Library Write-up DECUS NO. 8-472 

1 PROGRA M D ESCRIPT I ON 

In order to avoid the elaborate PS8 input-output programming, which pre¬ 
supposes a thorough knowledge of PS8 User Service Routines, we tried to design 
an automatic routine which would appear to the user as a simple character- 
oriented device like the TELETYPE. 

AJMS to the input part would return the next character, and a JMSto the output 
part would "print" it on the output-file and -device. 

The routine should for example, be able to call the COMMAND DECODER and 
detect when to close the output file. 

The routines were designed for a typical class of programs expecting one input 
source and one output drain, and working with 8 bit structures'only (ASCII; 
BINARY) 

In this class of files the terminating character CTRL/Z(232) plays an important 
role, making the following automatic concept possible: 



When entered for the first time, the INPUT part (PS8IN) calls the COMiMAND 
DECODER; fetches the device-handler; reads the first block; and takes the first 
character to return to the user. In successive calls, the routine reads blocks, 
takes characters from it etc. until a CTRL/Z is detected. It then opens the next 
input file and so on, until no input files remain. It then passes the CTRL/Z 
character for the first time, signaling the real end-of-file situation. 

The OUTPUT part (PS80UT) fetches the device handler and opens the output file 7 
when entered for the first time. It then writes the character away in the output 
buffer. In successive calls the output buffer will be filled and buffers will be 
written to the output device. 

Passing a CTRL/Z character to the OUTPUT part closes the output file, and 
causes an automatic return to the MONITOR. 


The main benefits of these building blocks are that they provide bug-free operation, 
and meaningful error messages when errors are detected. The programmer is also 
relieved from the bookkeeping of blocks on the input and output. They can also 
be used to adapt 4K programs to the PS8 programming system. 


k ) 


specified to the 


COMMAND DECODER 






The input to the COMMAND DECODER is: 

*outdev: FILE -«~indev: FILE 1, FILE 2,., FILE 9 

The use of the options (/,(), -) is still the same. If more than one output was 
specified, only the first one will be taken, and no error message results. The 
maximum number of input files is 9. 


The routines were compacted, each to fit into one physical page of core. They 
are page-relocatable at assembly-time, and they can easily be dimensioned with 
regard to buffer size and the place of one- and two-page handlers. By compacting 
the routines, however, some restrictions were implemented too: the routines must 
reside in FIELD 1, as is the case with the buffers. This was not felt as a major 
disadvantage. The routines are not restartable, however. 


2 HOW TO USE PS8I N and PS8 QUT 

An example of a program to perform the /A or /B option in PIP is attractively 
simple: 

START, CIF 10 

JMS I (PS8IN /call C.D. and fetch a char. 

CIF 10 

JMS I (PS80UT /output the char. 

JMP START 


Note that the exit to the PS8 monitor is also built-in: the last character (CTRL/Z) 
closes the output file, and then causes a jump to the monitor. 

If the input file has no CTRL/Z as a terminator, PS8IN reads all characters of the 
last block, and automatically generates one CTRL/Z when trying to read beyond 
the file limits. This occurs only once 1! 



Parameters can be set in the‘bser-equates" at the beginning of each module. 
For PS80UT the following applies: 

TWO PAG = 1 . . . . . allows a two-page handler to be loaded in core. The 

user himself must be sure that the handler area is in 
agreement with this statement. 

TWO PAG = ft .means that only one-page handlers are allowed. 
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HANDLE = 7200 


BUFOUT - 6600 
BLKOUT = 1 


) 

) 


Defines where the device-handler should be loaded in 
core. Note that device handlers are always loaded in 

FIELD 0. 

Define the buffer area. In this example a buffer of one 
BLOCK (= 2 pages) beginning at 16600 and ending at 
17200 is specified. 

Note that the buffer resides in FIELD 1, vvhich is a 
must. 

The buffer may, however, be located in th.e COMMAND 
DECODER area. 

One can use any multiple of 1 BLOCK as a buffer size. 


For PS8IN similar equates exist: 


INTPAG = 1 
INTPAG = 0 
HAND IN =7000 


BUFIN = 6200 
BLOKIN = 1 


) 

) 


PSEXT = 0123 


For a two-page handler. 

For an one-page handler. 

The beginning of the handler area. Be careful not 
to load over the monitor resident areas, as no protection 
against this offence exists. 

Define a buffers!ze of 1 BLOCK (2 pages) from 16200 to 
16600 in FIELD 1. 

, The input buffer also must reside in FIELD 1. It may, 
however, be located in the COMMAND DECODER area. 
The buffer size can be any multiple of 1 BLOCK. 

Defines a default extension (.AS) if no extension was 
specified in the input file. For example: if the user typed 
* SYS: TRY -s- SYS:TEM 

the COMMAND DECODER searches the filename 
TEM.AS prior to the filename without an extension. 
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PS8IN and PS80UT as structured in the available listings occupy core as 
follows: 


0 


FIELD 0 


7000 

7200 

7600 

7777 



1000 , 

16200 

16600 



INPUT 

BUFFER 

“Input 8 

OUTPUT 

HANDLER 

ONE 17200 
PAGE. 17400 

BUFFER 

OUTPUT 

PS8 OUT 

HANDLER 

17600 

PS8 IN 

“V 


MONITOR 

17777 

MONITOR 


When the user detects the CTRL/Z himself, he may suspend the termination of 
the program. He should, however, cause a monitor return with the CTRL/Z 
character to PS80UT, in order to close the file. 

If other devices were used in the program, he should clear the hardware flags 
before terminating the program. This is to prevent "unexpected interrupts" to occur 
in programs that do not use these devices, while running with the interrupt on. 

Although PS8IN and PS80UT were designed to run together, they can nevertheless 
be used separately. PS8IN, when used alone, will be quite self-supporting: it calls 
the COMMAND DECODER, and sets the JOB STATUS word to prevent the restart 
of the program. 

The use of PS80UT alone needs more help: as the command-decoder is not called 
automalically, the user should do so himself. He should also set the JOB STATUS 
word to prevent a restart of the program. 
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For a COMMAND DECODER call: 


CIF 1# 

JMS I (7700 
5 

PSEXT /Default extension 0123 = A.S 

/Return. 


To set the JOB STATUS word bit 2 (not restartable): 


CDF 0 
TAD I (7746 
AND (6777 
TAD (1000 
DCA I (7746 


/Do an inclusive OR. 


Instead of using the command decoder, the user can write to a fixed file on a 


fixed device, by filling in locations 17600 to 17604 of the output file table 
(chapter 3.4.1 of the PS8 software support manual). An example of a fixed output 


file, named TEM. FD on the system-device (device 1) follows below: 


17600 

0001 

/length undetermined; device^! 

17601 

2405 

A E 

17602 

1500 

/M 

17603 

0000 


17604 

0604 

/. FD 


For the device numbers see appendix 4.2. 


» 

Note that PS80UT can not be used to delete an existing file. The user can delete 
an existing (or not existing) file as follows: 


The user wants to delete the file TEM.FD on the system-device (device-number 1) 


TAD (1 
CIF 10 
JMS I (7700 
4 

NAME 

P 

NOP 


/DEVICE NUMBER 

/CALL USR 
/CLOSE 

/POINTER TO NAME "TEM.FD" 

/ZERO BLOCKS = DELETE 

/IF TEM.FD NOT FOUND IS O.K. TOO. 
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NAME, FILENAME TEM.FD 

Note that the 4-word name block should be located in the field of the 
USR-cal I. 

3 LIMI TA TIONS 

The limitations of PS3IN and PSSOUT are listed here, point by point 

1) The program works in FIELD 1 only; it may not be loaded into 10000-11777 
or 17600-17777. 

2) Input and output buffers in FIELD 1 only. They may, however, be located in 
the COMMAND DECODER area. 

3) Device-handlers in FIELD $ only (restriction of PS8). 

4) The program is not restartable. 

5) PSSOUT is not fully self-supporting (COMMAND DECODER) 
and JOB STATUS word) when used alone. 

6 ) Only ASCII and BINARY files can be processed. 

7) All error messages are fatal; they cause a MONITOR return. 

8 ) The size of the output file will always be a multiple of the output buffer. 
When closing a file, the remaining blocks v/ill be filled with zeroes. 

The use of small buffers minimizes this "rounding off". 

9) PS80UT cannot be used to delete a file. 
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4.1 A SUMMARY OF ERROR-MESSAGES 


All PS8IN and PS80UT error-message--, are fatal. They are printed by the user 

service routines in the following format: 

USER ERROR N AT XXXXX 

Where N is the error code, explained below, and XXXXX is related to a location 

in core where the error call came from. As all error calls come from the same 

2 origins in PS8IN and PS80UT, XXXXX has no meaning to the user. 

USER ERROR 1: The output-device handler could not be found; An attempt was 
made to load a 2-page handler into one page. 

USER ERROR 2: The output file could not be opened or closed; the device was a 
read only device; No room for output; two tentative files on 
this device; An illegal device name was specified. 

USER ERROR 3: Output file too long. 

USER ERROR 4: Write error in output. 

USER ERROR 5: The input-device handler could not be found. 

Read error ?n input. 


USER ERROR 6: 
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4.2 DEVICENNUMBERS IN PS8 


4 


#* 


DEVICE 

NUMBER 

DEVICE 

01 

SYSTEM-DEVICE 

02 

DEFAULT DEVICE "1 

03 

TELETYPE PRINTER 

04 

LINE PRINTER 

05 

DECTAPE 0 

06 

" 1 

07 

" 2 

10 

" 3 

11 

" 4 

12 

" 5 

13 

" 6 

14 

" 7 

15 

PAPERTAPE PUNCH 

16 

PAPERTAPE READER 

17 

CARD READER 
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The author(s) will be grateful when detected errors in both software performance 
and the manual are reported back. 

In such a case, please write to the author(s): 

MEDICAL BIOLOGICAL LABORATORY TNO 
Computer department c/o Mr. J.F. Anthoni 
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